From d9d706c47e5fd3f26bb35ff3b1aa68d28da84ddc Mon Sep 17 00:00:00 2001 From: robertl Date: Sun, 26 Nov 2006 20:55:50 +0000 Subject: [PATCH] 'Tart up' more of the doc. --- xmldoc/chapters/preface.xml | 15 +++++------ xmldoc/chapters/use.xml | 49 ++++++++++++++++++++++++++++++++---- xmldoc/formats/compegps.xml | 2 +- xmldoc/formats/gtrnctr.xml | 3 +-- xmldoc/formats/html.xml | 11 +++++--- xmldoc/formats/magellan1.xml | 6 +++++ xmldoc/formats/magellanx.xml | 4 +-- xmldoc/formats/maggeo.xml | 5 ++-- xmldoc/formats/tmpro.xml | 2 +- 9 files changed, 74 insertions(+), 23 deletions(-) diff --git a/xmldoc/chapters/preface.xml b/xmldoc/chapters/preface.xml index c15306d7f..164c1c5eb 100644 --- a/xmldoc/chapters/preface.xml +++ b/xmldoc/chapters/preface.xml @@ -13,13 +13,14 @@ alternate formats.
The Solution - I needed to convert waypoints between a couple of formats, so I + The original author of GPSBabel, Robert Lipe, needed to convert waypoints between a couple of formats, so he whipped up a converter and based it on an extensible foundation so -that it was easy to add new formats. Most file formats added so far -have taken under 200 lines of reasonable ISO C so they can be stamped -out pretty trivially. Formats that are ASCII text delimited in some -fixed way can be added with no programming at all via our 'style' -mechanism. - +that it was easy to add new formats and made the program freely available. Many others have contributed to the program since then. + Most file formats added so far have taken under 200 + lines of reasonable ISO C so they can be stamped + out pretty trivially. Formats that are ASCII text delimited in some + fixed way can be added with no programming at all via our + style mechanism. +
diff --git a/xmldoc/chapters/use.xml b/xmldoc/chapters/use.xml index df0109323..4b7a444dc 100644 --- a/xmldoc/chapters/use.xml +++ b/xmldoc/chapters/use.xml @@ -2,13 +2,10 @@ Usage Invocation - Invocation was meant to be flexible. Unfortunately, - that can sometimes lead to unwieldy command lines. - If you're using GPSBabel, you will need to know how to do at least two things: read data from a file, and write it to another file. There are four basic -commands you need to know to do those things: +options you need to know to do those things: @@ -43,6 +40,11 @@ name that you would use on the command line follows the format name in parentheses. +Options are always processed in order from left to right. +In practical terms, this means that things you want to read should appear +in the command before things you want to write. + + The filename parameters specify the name of a file to be read or written. @@ -74,6 +76,35 @@ name of a file to be read or written. gpsbabel -s -i geo -f geocaching.loc -o magellan -F /dev/ttyS0 gpsbabel -s -i geo -f geocaching.loc -o magellan -F com1 + + Suboptions + + Many of the available format options in GPSBabel can themselves + take options. While we try to make all the formats do the most + sensible thing possible without any extra options, this allows + great power and flexibility in the operation of the program. + + + Suboptions are comma separated and immediately follow the option + itself. The available suboptions are listed on the individual + format pages. We'll make an example from : + + gpsbabel -i gpx -f file.gpx -o kml,deficon="file://myicon.png",lines=0 -F one.kml -o kml -F two.kml + + This command will read the GPX file file.gpx + and create two KML files. one.kml will + have the given icon and no lines between track and routepoints. + two.kml will be created with the defaults used + in the KML writer. + + + Suboptions for the various formats allow you to change serial speeds, + pass arguments to filters, change the type of file written, override + icon defaults, and lots of other things. The suboptions for each + filetype are documented on the page in this document that describes + the option itself. + + Advanced Usage Argument are processed in the order they appear on the command @@ -110,7 +141,7 @@ merged data to multiple destinations. Route and Track Modes - Most formats will make reasonable attempt to work + Most formats will make a reasonable attempt to work transparently with waypoints, tracks, and routes. Some formats, like 'garmin' and 'magellan' require the -t flag to work with tracks and -r to work with @@ -123,6 +154,14 @@ merged data to multiple destinations. to handle every possible hazard that can be encountered during a conversion. If you're merging or converting files of similar limitations, things work very well. + Many of those hazards can be overcome with our filters + but there are often compromises to be made. For example, if you + have a GPX route that contains 150 turn points but you're sending + the route to a GPX that supports only 30 turnpoints, something has + to go. One might use our 'simplify' filter to produce a route that + retained the 30 most mathematically significant turnpoints but that + may not really be the route you had in mind. + Tracks and routes will sometimes be converted to a list of waypoints when necessary, f.i. when writing into one of the CSV formats. The inverse operation is not supported diff --git a/xmldoc/formats/compegps.xml b/xmldoc/formats/compegps.xml index 354b783ea..177a6a57e 100644 --- a/xmldoc/formats/compegps.xml +++ b/xmldoc/formats/compegps.xml @@ -1,5 +1,5 @@ -These data files are "character" separated text files like +CompeGPS data files are "character" separated text files like the pcx format. "Character" means special data lines can have their own separator. diff --git a/xmldoc/formats/gtrnctr.xml b/xmldoc/formats/gtrnctr.xml index f59087135..34c59528d 100644 --- a/xmldoc/formats/gtrnctr.xml +++ b/xmldoc/formats/gtrnctr.xml @@ -1,6 +1,5 @@ -Garmin Training Center is the successor to Garmin' Logbook program -for their workout units. It is a free upgrade. +GPSBabel has limited support for Garmin Training Center files. That program is the successor to Garmin' Logbook program for their workout units. It is a free upgrade. This format is somewhat underachieving in GPSBabel. It is a write-only diff --git a/xmldoc/formats/html.xml b/xmldoc/formats/html.xml index da0de56a7..1735a6b3d 100644 --- a/xmldoc/formats/html.xml +++ b/xmldoc/formats/html.xml @@ -1,7 +1,12 @@ - HTML output generates a single HTML file of all of the + GPSBabel's HTML output generates a single HTML file of all of the waypoints in the input file. It supports a number of Groundspeak GPX -extensions, as well as filters out potentially harmful HTML from the -input file while maintaining almost all of the source HTML formatting. +extensions and filters out potentially harmful HTML from the +input file while maintaining almost all of the source HTML formatting. +This makes this format well suited for generating HTML to hand to programs +like Plucker for putting in a PDA and especially so for "paperless caching" +for Geocachers with pocket queries. + +This format is similar to the text format. The following command line reads a GPX file with Groundspeak extensions and writes an HTML file with encrypted hints diff --git a/xmldoc/formats/magellan1.xml b/xmldoc/formats/magellan1.xml index 166e5a870..b86c1904b 100644 --- a/xmldoc/formats/magellan1.xml +++ b/xmldoc/formats/magellan1.xml @@ -38,3 +38,9 @@ The RoadMate family of products is not supported. a file, either on local filesystem or on a mounted flash card reader, will result in the file-based format being used. + + Users of the Explorist generation of receivers should probably + prefer to use the magellanx + format over this one. + + diff --git a/xmldoc/formats/magellanx.xml b/xmldoc/formats/magellanx.xml index b2f0e712f..ffb219fb5 100644 --- a/xmldoc/formats/magellanx.xml +++ b/xmldoc/formats/magellanx.xml @@ -1,7 +1,7 @@ This is the SD card format used by the Magellan Explorist 400, - 500, 600, and XL and internally on those devices plus the - Explorist 210. Storeed waypoints are identical to the Magellan SD format + Explorist 500, Explorist 600, and Explorist XL and internally on those devices plus the + Explorist 210. Stored waypoints are identical to the Magellan SD format used by Meridian, but the newer models allow longer waypoint names. Routes are subtly different. diff --git a/xmldoc/formats/maggeo.xml b/xmldoc/formats/maggeo.xml index ea97b5352..43aa3c392 100644 --- a/xmldoc/formats/maggeo.xml +++ b/xmldoc/formats/maggeo.xml @@ -1,8 +1,9 @@ - The SD card format used by the Magellan > 400, -500, 600, 210, and XL to describe geocaches. Notice what while the format can + This format support the on-card format used by the Magellan Explorist 400, +Explorist 500, Explorist 600, Explorist 210, and Explorist XL +to describe geocaches. Notice what while the format can hold an infinite number of geocaches, the unit will read and silently discard all but 200 geocache POIs at a time. You should name any file created with this format with a diff --git a/xmldoc/formats/tmpro.xml b/xmldoc/formats/tmpro.xml index cf02509db..255b92762 100644 --- a/xmldoc/formats/tmpro.xml +++ b/xmldoc/formats/tmpro.xml @@ -2,7 +2,7 @@ Reads and writes places files for -use in TopoMapPro places files). As this file +use in TopoMapPro places files. As this file type can store links other than web links, anything that is not a http url will be discarded. Note that this does not do datum conversions, so if your input file does not have WGS84/NZGD2000 data, your output -- 2.30.2